Skip to content

fix(install): install mliport into .venv-nep; NEP README/docs integration (#61) - #89

Merged
hydrogen1222 merged 6 commits into
mainfrom
fix/nep-installer-mliport-and-docs
Nov 7, 2026
Merged

hydrogen1222 merged 6 commits into
mainfrom
fix/nep-installer-mliport-and-docs

Conversation

@hydrogen1222

@hydrogen1222 hydrogen1222 commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

Tracking: #61 (not closed by this PR; #75 untouched).

状态:head fe93113 上全部 14 项 CI 通过(含新增真实安装 job installer-real-nep、lint、docs 检查)。未合并,等你审阅。 CI run: https://github.com/hydrogen1222/mliport/actions/runs/42327516375

问题

  • P0:plan.py::_nep_steps() 只装 calorine / ASE / numpy,没有装 mliport 本体,verify 阶段调用 .venv-nep/bin/mliport 时 FileNotFoundError。inventory 阶段之所以没提前暴露,是因为 install_mliport.sh 会导出 PYTHONPATH。
  • 同一处还有两个隐藏缺陷:NEP 步骤用 env={"PIP_EXTRA_INDEX_URL": ...}(托管源 profile 会清掉 PIP_*/UV_*),并读取不存在的 profile.index_url,所以 --source china* / offline 对 NEP 一直被静默忽略。
  • P1:README 无 NEP 内容;生成的环境表把 calorine==4.1 (12.9) 写成 NumPy 12.9,实际 12.9 是编译 gpumd 的 CUDA Toolkit。

修改

  • _nep_steps:与其他后端同一路径(_uv_pip + build_package_source_args),一次解析装入 -e ./mliport[analysis-all] 与 calorine==4.1(NumPy/ASE 交给解析器,不手写 pin)。仍是独立 .venv-nep,NEP 仍需显式 --engines nep。
  • 新增 runtime_stack_text(),生成表改为"NumPy/ASE 由安装器解析;gpumd 用 CUDA Toolkit 12.9 编译"。
  • README.md/README_CN.md/mliport/README.md、docs/installation*.md、docs/backends/nep*.md、CHANGELOG.md、安装脚本帮助:NEP 说明、安装命令、环境表、示例、限制;手动安装路线补上 mliport。
  • 其他后端的 plan 逐字节不变(有测试)。

测试

  • 无网络单元测试(test_install_plan.py 等):NEP 含 editable 安装与 pin、步骤顺序、official/china/offline/custom、--clean 只删 .venv-nep、多后端隔离、其他后端不受影响、文档/README 一致性。
  • 真实安装(test_install_nep_real.py,MLIPORT_REAL_INSTALL=1,新 CI job installer-real-nep):真实执行 scripts/install_mliport.sh;.venv-nep/bin/mliport 存在且可执行;在干净环境(无 PYTHONPATH)运行 doctor;独立环境;重复安装与 --clean;offline 暖缓存重装;中国镜像(uv shim 记录真实调用);缺 gpumd(cpu 通过、cuda 报错点名 gpumd、MLIPORT_GPUMD_COMMAND 假 gpumd 通过);用 nvidia-smi shim 模拟 GPU 主机。

真实安装日志(GitHub Actions installer-real-nep,ubuntu,Python 3.12,真实网络;完整日志在该 job 的 “Print install logs” 步骤和 nep-install-logs artifact)

bash scripts/install_mliport.sh --engines nep --non-interactive --device cpu --source official(干净环境,无 PYTHONPATH)→ exit=0:

[mliport] [venv] Create .venv-nep for NEP (Calorine / GPUMD)
[mliport] [constraints] Freeze NEP (Calorine / GPUMD) dependency contract
[mliport] [pip] Install NEP (Calorine / GPUMD) ASE runtime (pinned calorine + editable mliport)
[mliport] [check] ... [inventory] ... [verify] Verify NEP (Calorine / GPUMD)
[mliport] [launcher] created .../repo/bin/mliport-nep
[mliport] All 6 steps completed.
 + ase==3.29.0   + calorine==4.1   + mliport==2.0.0b4 (from file:///.../repo/mliport)   + numpy==2.5.4
  NEP package        calorine 4.1      ✓
  Engine runtime     calorine.calculators compute succeeded  ✓
 Environment checks passed for NEP on CPU.

其余真实运行(12 项测试全部通过):

  • .venv-nep/bin/mliport 存在且可执行,--help 正常;import mliport 指向工作区 editable 副本;calorine==4.1。
  • 隔离:只创建 .venv-nep;环境里没有 torch / mace / fairchem / deepmd / tensorflow;无其他后端启动器。
  • 缺 gpumd:doctor --device cpu 通过;--device cuda 退出码 1,RuntimeError: GPU NEP (Calorine GPUNEP or native gpumd) requires a gpumd executable; none was found on PATH or via MLIPORT_GPUMD_COMMAND;用 MLIPORT_GPUMD_COMMAND 指向(假)gpumd 则通过;只设 NEP_GPUMD_COMMAND 不通过(doctor 不读它)。
  • GPU 主机模拟(nvidia-smi shim 报告 V100,--device auto):6 步里前 5 步成功,verify 以 gpumd 缺失失败(退出 1),环境已装但不写 bin/mliport-nep。
  • 不加 --clean 重复安装:在建 venv 一步停下(A virtual environment already exists at: .venv-nep),原环境和 marker 文件未动,doctor 仍通过。
  • --clean 重装:只重建 .venv-nep,旁边的 .venv-bystander 未动。
  • --source offline --clean(暖缓存):成功。
  • --source china(uv shim 记录调用):NEP 的 pip install -e ./mliport[analysis-all] 带 --index-url https://mirrors.tuna.tsinghua.edu.cn/...;CI 能访问 TUNA,安装成功,exit 0。

已知限制 / 如实说明

  • 开发沙箱无网络、无 ase、无 GPU,真实安装只在 GitHub Actions 里跑;本地只跑了无网络测试(132 passed,12 skipped)。全量测试在沙箱里的 44 failed / 64 errors 与基线逐项相同(缺 ase)。
  • doctor 只读 MLIPORT_GPUMD_COMMAND,不读 NEP_GPUMD_COMMAND(运行时用后者)。这是已存在的不一致,本 PR 只在文档里写准确,未改行为。
  • GPU 主机上 --device auto|cuda 时收尾 doctor 要求 gpumd,没有则安装在此失败(fail-closed,环境已装好但 bin/mliport-nep 不写出);文档已说明,--device cpu 不受影响。
  • 安装器仍不编译 gpumd。
  • 既有行为(本 PR 未改):① 所有后端的计划在 .venv-* 已存在时,不加 --clean 重跑都会停在建环境一步(uv venv 无 --allow-existing),之前文档没说,现已在 docs/installation*.md 写明;是否让它幂等是另一个决定。② 机器上没有 nvidia-smi 时 doctor --device cuda 会抛 traceback(nvidia-smi failed while resolving a GPU device),到不了 gpumd 检查;这是所有引擎共用的 _probe_environment 行为,真实测试里用 nvidia-smi shim 绕开观察 gpumd 路径。

DATA IMPACT

无。不改任何模型、数值、轨迹或分析结果;只改 NEP 的安装计划与文档。其他后端的安装计划不变。

https://claude.ai/code/session_01GYQHUEKJ91XQC4Hzj11Q1X


Generated by Claude Code

…gration (#61)

P0: _nep_steps() installed only calorine, ASE and numpy, so the verify stage
failed with FileNotFoundError on .venv-nep/bin/mliport (the inventory stage
only worked because the bootstrap script leaks PYTHONPATH). The NEP step is now
one resolver run with editable ./mliport[analysis-all] plus the pinned
calorine==4.1, built from the same _uv_pip / build_package_source_args path as
the other backends. This also makes --source china/offline/custom effective for
NEP: the old PIP_EXTRA_INDEX_URL env was stripped by the managed source
profiles and profile.index_url does not exist.

P1: README.md/README_CN.md gain NEP install, environment table, example and
limits; the generated environment table no longer prints "calorine==4.1 (12.9)"
(NumPy/ASE resolved by the installer vs CUDA Toolkit 12.9 used to build gpumd);
the manual NEP install route includes mliport; docs state that doctor reads
MLIPORT_GPUMD_COMMAND (not NEP_GPUMD_COMMAND) and that a GPU-host install
without gpumd stops at the closing doctor.

Tests: plan-level NEP tests (editable install, pin, order, mirror/offline/custom,
clean scope, isolation, other backends unchanged), docs consistency tests, and
a gated real-install suite (MLIPORT_REAL_INSTALL=1) run by the new
installer-real-nep CI job.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GYQHUEKJ91XQC4Hzj11Q1X
…iff probe

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GYQHUEKJ91XQC4Hzj11Q1X
…lean; drop probe

Real CI run showed: doctor --device cuda needs nvidia-smi before it reaches the
gpumd check (use an nvidia-smi shim), and a plain re-run stops at venv creation
for every backend (documented, test pinned to it).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GYQHUEKJ91XQC4Hzj11Q1X
…d and full inventory)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GYQHUEKJ91XQC4Hzj11Q1X
… ends in index,uuid)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GYQHUEKJ91XQC4Hzj11Q1X
@hydrogen1222
hydrogen1222 merged commit 5195e6c into main Nov 7, 2026
14 checks passed
@hydrogen1222
hydrogen1222 deleted the fix/nep-installer-mliport-and-docs branch November 7, 2026 02:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants